home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1999 July: Mac OS SDK / Dev.CD Jul 99 SDK1.toast / Development Kits / Mac OS / QuickDraw3D 1.6 SDK / Mac Interfaces / CIncludes / QD3DRenderer.h < prev    next >
Encoding:
C/C++ Source or Header  |  1999-05-18  |  42.7 KB  |  1,257 lines  |  [TEXT/MPS ]
  1. /*
  2.      File:        QD3DRenderer.h
  3.  
  4.      Contains:    Q3Renderer types and routines                                          
  5.  
  6.      Version:    Technology:    Quickdraw 3D 1.6
  7.                  Release:    QuickTime 4.0
  8.  
  9.      Copyright:    © 1995-1999 by Apple Computer, Inc., all rights reserved.
  10.  
  11.      Bugs?:        For bug reports, consult the following page on
  12.                  the World Wide Web:
  13.  
  14.                      http://developer.apple.com/bugreporter/
  15.  
  16. */
  17. #ifndef __QD3DRENDERER__
  18. #define __QD3DRENDERER__
  19.  
  20. #ifndef __QD3D__
  21. #include <QD3D.h>
  22. #endif
  23. #ifndef __QD3DSET__
  24. #include <QD3DSet.h>
  25. #endif
  26. #ifndef __QD3DVIEW__
  27. #include <QD3DView.h>
  28. #endif
  29. #ifndef __RAVE__
  30. #include <RAVE.h>
  31. #endif
  32.  
  33. #if TARGET_OS_MAC
  34. #ifndef __EVENTS__
  35. #include <Events.h>
  36. #endif
  37. #endif  /* TARGET_OS_MAC */
  38.  
  39.  
  40.  
  41. #if PRAGMA_ONCE
  42. #pragma once
  43. #endif
  44.  
  45. #ifdef __cplusplus
  46. extern "C" {
  47. #endif
  48.  
  49. #if PRAGMA_IMPORT
  50. #pragma import on
  51. #endif
  52.  
  53. #if PRAGMA_STRUCT_ALIGN
  54.     #pragma options align=power
  55. #elif PRAGMA_STRUCT_PACKPUSH
  56.     #pragma pack(push, 2)
  57. #elif PRAGMA_STRUCT_PACK
  58.     #pragma pack(2)
  59. #endif
  60.  
  61. #if PRAGMA_ENUM_ALWAYSINT
  62.     #pragma enumsalwaysint on
  63. #elif PRAGMA_ENUM_OPTIONS
  64.     #pragma option enum=int
  65. #elif PRAGMA_ENUM_PACK
  66.     #if __option(pack_enums)
  67.         #define PRAGMA_ENUM_PACK__QD3DRENDERER__
  68.     #endif
  69.     #pragma options(!pack_enums)
  70. #endif
  71.  
  72. /******************************************************************************
  73.  **                                                                             **
  74.  **                            User Interface Things                             **
  75.  **                                                                             **
  76.  *****************************************************************************/
  77. #if TARGET_OS_MAC
  78. /*
  79.  *  A callback to an application's event handling code. This is needed to    
  80.  *  support movable modal dialogs. The dialog's event filter calls this      
  81.  *  callback with events it does not handle.                                 
  82.  *  If an application handles the event it should return kQ3True.            
  83.  *  If the application does not handle the event it must return kQ3False and 
  84.  *  the dialog's event filter will pass the event to the system unhandled.   
  85.  */
  86. typedef CALLBACK_API_C( TQ3Boolean , TQ3MacOSDialogEventHandler )(const EventRecord *event);
  87.  
  88. struct TQ3DialogAnchor {
  89.     TQ3MacOSDialogEventHandler         clientEventHandler;
  90. };
  91. typedef struct TQ3DialogAnchor            TQ3DialogAnchor;
  92. #endif  /* TARGET_OS_MAC */
  93.  
  94. #if TARGET_OS_WIN32
  95.  
  96. struct TQ3DialogAnchor {
  97.     HWND                             ownerWindow;
  98. };
  99. typedef struct TQ3DialogAnchor            TQ3DialogAnchor;
  100. #endif  /* TARGET_OS_WIN32 */
  101.  
  102. #if TARGET_OS_UNIX
  103.  
  104. struct TQ3DialogAnchor {
  105.     void *                            notUsed;                    /* place holder */
  106. };
  107. typedef struct TQ3DialogAnchor            TQ3DialogAnchor;
  108. #endif  /* TARGET_OS_UNIX */
  109.  
  110. /******************************************************************************
  111.  **                                                                             **
  112.  **                            Renderer Functions                                 **
  113.  **                                                                             **
  114.  *****************************************************************************/
  115. EXTERN_API_C( TQ3RendererObject )
  116. Q3Renderer_NewFromType            (TQ3ObjectType             rendererObjectType);
  117.  
  118. EXTERN_API_C( TQ3ObjectType )
  119. Q3Renderer_GetType                (TQ3RendererObject         renderer);
  120.  
  121.  
  122. /* Q3Renderer_Flush has been replaced by Q3View_Flush */
  123. /* Q3Renderer_Sync has been replaced by Q3View_Sync */
  124.  
  125. /*
  126.  *    Q3Renderer_IsInteractive
  127.  *        Determine if this renderer is intended to be used interactively.
  128.  */
  129. EXTERN_API_C( TQ3Boolean )
  130. Q3Renderer_IsInteractive        (TQ3RendererObject         renderer);
  131.  
  132.  
  133. /*
  134.  *    Q3Renderer_HasModalConfigure
  135.  *        Determine if this renderer has a modal settings dialog.
  136.  *
  137.  *    Q3Renderer_ModalConfigure
  138.  *        Have the renderer pop up a modal dialog box to configure its settings.
  139.  *    dialogAnchor - is platform specific data passed by the client to support
  140.  *      movable modal dialogs. 
  141.  *    MacOS: this is a callback to the calling application's event handler.
  142.  *      The renderer calls this function with events not handled by the 
  143.  *      settings dialog. This is necessary in order to support movable modal 
  144.  *      dialogs. An application's event handler must return kQ3True if it 
  145.  *      handles the event passed to the callback or kQ3False if not. 
  146.  *      An application which doesn't want to support a movable modal configure
  147.  *      dialog should pass NULL for the clientEventHandler of TQ3DialogAnchor.
  148.  *    Win32: this is the HWND of the owning window (typically an application's
  149.  *      main window).
  150.  *  canceled - returns a boolean inditacating that the user canceled the 
  151.  *    dialog.
  152.  *      
  153.  */
  154. EXTERN_API_C( TQ3Boolean )
  155. Q3Renderer_HasModalConfigure    (TQ3RendererObject         renderer);
  156.  
  157. EXTERN_API_C( TQ3Status )
  158. Q3Renderer_ModalConfigure        (TQ3RendererObject         renderer,
  159.                                  TQ3DialogAnchor         dialogAnchor,
  160.                                  TQ3Boolean *            canceled);
  161.  
  162. /*
  163.  *    Q3RendererClass_GetNickNameString
  164.  *        Allows an application to get a renderers name string, the 
  165.  *        renderer is responsible for storing this in a localizable format
  166.  *        for example as a resource.  This string can then be used to provide
  167.  *        a selection mechanism for an application (for example in a menu).
  168.  *
  169.  *        If this call returns nil in the supplied string, then the App may 
  170.  *         choose to use the class name for the renderer.  You should always 
  171.  *        try to get the name string before using the class name, since the
  172.  *        class name is not localizable.
  173.  */
  174. EXTERN_API_C( TQ3Status )
  175. Q3RendererClass_GetNickNameString (TQ3ObjectType         rendererClassType,
  176.                                  TQ3ObjectClassNameString  rendererClassString);
  177.  
  178.  
  179. /*
  180.  *    Q3Renderer_GetConfigurationData
  181.  *        Allows an application to collect private renderer configuration data
  182.  *      which it will then save. For example in a preference file or in a 
  183.  *        style template. An application should tag this data with the 
  184.  *        Renderer's object  name.
  185.  *    
  186.  *        if dataBuffer is NULL actualDataSize returns the required size in 
  187.  *        bytes of a data buffer large enough to store private data. 
  188.  *
  189.  *      bufferSize is the actual size of the memory block pointed to by 
  190.  *        dataBuffer
  191.  *
  192.  *        actualDataSize - on return the actual number of bytes written to the 
  193.  *        buffer or if dataBuffer is NULL the required size of dataBuffer
  194.  * 
  195.  */
  196. EXTERN_API_C( TQ3Status )
  197. Q3Renderer_GetConfigurationData    (TQ3RendererObject         renderer,
  198.                                  unsigned char *        dataBuffer,
  199.                                  unsigned long             bufferSize,
  200.                                  unsigned long *        actualDataSize);
  201.  
  202. EXTERN_API_C( TQ3Status )
  203. Q3Renderer_SetConfigurationData    (TQ3RendererObject         renderer,
  204.                                  unsigned char *        dataBuffer,
  205.                                  unsigned long             bufferSize);
  206.  
  207.  
  208.  
  209. /******************************************************************************
  210.  **                                                                             **
  211.  **                        Interactive Renderer Specific Functions                 **
  212.  **                                                                             **
  213.  *****************************************************************************/
  214. /* CSG IDs attribute */
  215. #define kQ3AttributeTypeConstructiveSolidGeometryID        Q3_OBJECT_TYPE('c','s','g','i')
  216. /* Object IDs, to be applied as attributes on geometries */
  217. #define kQ3SolidGeometryObjNone (-1)
  218. #define kQ3SolidGeometryObjA     0
  219. #define kQ3SolidGeometryObjB     1
  220. #define kQ3SolidGeometryObjC     2
  221. #define kQ3SolidGeometryObjD     3
  222. #define kQ3SolidGeometryObjE     4
  223. /* Possible CSG equations */
  224.  
  225. enum TQ3CSGEquation {
  226.     kQ3CSGEquationAandB            = (long)0x88888888,
  227.     kQ3CSGEquationAandnotB        = 0x22222222,
  228.     kQ3CSGEquationAanBonCad        = 0x2F222F22,
  229.     kQ3CSGEquationnotAandB        = 0x44444444,
  230.     kQ3CSGEquationnAaBorCanB    = 0x74747474
  231. };
  232. typedef enum TQ3CSGEquation TQ3CSGEquation;
  233.  
  234. EXTERN_API_C( TQ3Status )
  235. Q3InteractiveRenderer_SetCSGEquation (TQ3RendererObject  renderer,
  236.                                  TQ3CSGEquation         equation);
  237.  
  238. EXTERN_API_C( TQ3Status )
  239. Q3InteractiveRenderer_GetCSGEquation (TQ3RendererObject  renderer,
  240.                                  TQ3CSGEquation *        equation);
  241.  
  242. EXTERN_API_C( TQ3Status )
  243. Q3InteractiveRenderer_SetPreferences (TQ3RendererObject  renderer,
  244.                                  long                     vendorID,
  245.                                  long                     engineID);
  246.  
  247. EXTERN_API_C( TQ3Status )
  248. Q3InteractiveRenderer_GetPreferences (TQ3RendererObject  renderer,
  249.                                  long *                    vendorID,
  250.                                  long *                    engineID);
  251.  
  252. EXTERN_API_C( TQ3Status )
  253. Q3InteractiveRenderer_SetDoubleBufferBypass (TQ3RendererObject  renderer,
  254.                                  TQ3Boolean             bypass);
  255.  
  256. EXTERN_API_C( TQ3Status )
  257. Q3InteractiveRenderer_GetDoubleBufferBypass (TQ3RendererObject  renderer,
  258.                                  TQ3Boolean *            bypass);
  259.  
  260. EXTERN_API_C( TQ3Status )
  261. Q3InteractiveRenderer_SetRAVEContextHints (TQ3RendererObject  renderer,
  262.                                  unsigned long             RAVEContextHints);
  263.  
  264. EXTERN_API_C( TQ3Status )
  265. Q3InteractiveRenderer_GetRAVEContextHints (TQ3RendererObject  renderer,
  266.                                  unsigned long *        RAVEContextHints);
  267.  
  268. EXTERN_API_C( TQ3Status )
  269. Q3InteractiveRenderer_SetRAVETextureFilter (TQ3RendererObject  renderer,
  270.                                  unsigned long             RAVEtextureFilterValue);
  271.  
  272. EXTERN_API_C( TQ3Status )
  273. Q3InteractiveRenderer_GetRAVETextureFilter (TQ3RendererObject  renderer,
  274.                                  unsigned long *        RAVEtextureFilterValue);
  275.  
  276. EXTERN_API_C( TQ3Status )
  277. Q3InteractiveRenderer_CountRAVEDrawContexts (TQ3RendererObject  renderer,
  278.                                  unsigned long *        numRAVEContexts);
  279.  
  280. typedef CALLBACK_API_C( void , TQ3RaveDestroyCallback )(TQ3RendererObject renderer);
  281. EXTERN_API_C( TQ3Status )
  282. Q3InteractiveRenderer_GetRAVEDrawContexts (TQ3RendererObject  renderer,
  283.                                  TQADrawContext **        raveDrawContextList,
  284.                                  TQAEngine **            raveDrawingEnginesList,
  285.                                  unsigned long *        numRAVEContexts,
  286.                                  TQ3RaveDestroyCallback  raveDestroyCallback);
  287.  
  288.  
  289.  
  290.  
  291. /******************************************************************************
  292.  **                                                                             **
  293.  **                            Renderer View Tools                                 **
  294.  **                                                                             **
  295.  **                    You may only call these methods from a plug-in             **
  296.  **                                                                             **
  297.  *****************************************************************************/
  298. /*
  299.  *    Call by a renderer to call the user "idle" method, with progress 
  300.  *    information.
  301.  *    
  302.  *    Pass in (view, 0, n) on first call
  303.  *    Pass in (view, 1..n-1, n) during rendering
  304.  *    Pass in (view, n, n) upon completion
  305.  *    
  306.  *    Note: The user must have supplied an idleProgress method with 
  307.  *    Q3XView_SetIdleProgressMethod. Otherwise, the generic idle method is
  308.  *    called with no progress data. e.g. the Q3View_SetIdleMethod method
  309.  *    is called instead. (current and final are ignored, essentially.)
  310.  *
  311.  *    Returns kQ3Failure if rendering is cancelled.
  312.  */
  313. EXTERN_API_C( TQ3Status )
  314. Q3XView_IdleProgress            (TQ3ViewObject             view,
  315.                                  unsigned long             current,
  316.                                  unsigned long             completed);
  317.  
  318. /*
  319.  *    Called by an asynchronous renderer when it completes a frame.
  320.  */
  321. EXTERN_API_C( TQ3Status )
  322. Q3XView_EndFrame                (TQ3ViewObject             view);
  323.  
  324.  
  325. /******************************************************************************
  326.  **                                                                             **
  327.  **                            Renderer AttributeSet Tools                         **
  328.  **                                                                             **
  329.  **                    You may only call these methods from a plug-in             **
  330.  **                                                                             **
  331.  *****************************************************************************/
  332. /*
  333.  *    Faster access to geometry attribute sets.
  334.  *    
  335.  *    Returns pointer to INTERNAL data structure for elements and attributes
  336.  *    in an attributeSet, or NULL if no attribute exists.
  337.  *    
  338.  *    For attributes of type kQ3AttributeType..., the internal data structure
  339.  *    is identical to the data structure used in Q3AttributeSet_Add.
  340.  */
  341. EXTERN_API_C( void *)
  342. Q3XAttributeSet_GetPointer        (TQ3AttributeSet         attributeSet,
  343.                                  TQ3AttributeType         attributeType);
  344.  
  345.  
  346. enum {
  347.     kQ3XAttributeMaskNone        = 0L,
  348.     kQ3XAttributeMaskSurfaceUV    = 1 << (kQ3AttributeTypeSurfaceUV - 1),
  349.     kQ3XAttributeMaskShadingUV    = 1 << (kQ3AttributeTypeShadingUV - 1),
  350.     kQ3XAttributeMaskNormal        = 1 << (kQ3AttributeTypeNormal - 1),
  351.     kQ3XAttributeMaskAmbientCoefficient = 1 << (kQ3AttributeTypeAmbientCoefficient - 1),
  352.     kQ3XAttributeMaskDiffuseColor = 1 << (kQ3AttributeTypeDiffuseColor - 1),
  353.     kQ3XAttributeMaskSpecularColor = 1 << (kQ3AttributeTypeSpecularColor - 1),
  354.     kQ3XAttributeMaskSpecularControl = 1 << (kQ3AttributeTypeSpecularControl - 1),
  355.     kQ3XAttributeMaskTransparencyColor = 1 << (kQ3AttributeTypeTransparencyColor - 1),
  356.     kQ3XAttributeMaskSurfaceTangent = 1 << (kQ3AttributeTypeSurfaceTangent - 1),
  357.     kQ3XAttributeMaskHighlightState = 1 << (kQ3AttributeTypeHighlightState - 1),
  358.     kQ3XAttributeMaskSurfaceShader = 1 << (kQ3AttributeTypeSurfaceShader - 1),
  359.     kQ3XAttributeMaskCustomAttribute = (long)0x80000000,
  360.     kQ3XAttributeMaskAll        = (long)0x800007FF,
  361.     kQ3XAttributeMaskInherited    = 0x03FF,
  362.     kQ3XAttributeMaskInterpolated = kQ3XAttributeMaskSurfaceUV | kQ3XAttributeMaskShadingUV | kQ3XAttributeMaskNormal | kQ3XAttributeMaskAmbientCoefficient | kQ3XAttributeMaskDiffuseColor | kQ3XAttributeMaskSpecularColor | kQ3XAttributeMaskSpecularControl | kQ3XAttributeMaskTransparencyColor | kQ3XAttributeMaskSurfaceTangent
  363. };
  364.  
  365.  
  366. typedef unsigned long                     TQ3XAttributeMask;
  367. EXTERN_API_C( TQ3XAttributeMask )
  368. Q3XAttributeSet_GetMask            (TQ3AttributeSet         attributeSet);
  369.  
  370.  
  371. /******************************************************************************
  372.  **                                                                             **
  373.  **                            Renderer Draw Context Tools                         **
  374.  **                                                                             **
  375.  *****************************************************************************/
  376. typedef struct OpaqueTQ3XDrawRegion*     TQ3XDrawRegion;
  377. EXTERN_API_C( TQ3Status )
  378. Q3XDrawContext_GetDrawRegion    (TQ3DrawContextObject     drawContext,
  379.                                  TQ3XDrawRegion *        drawRegion);
  380.  
  381.  
  382. enum TQ3XDrawContextValidationMasks {
  383.     kQ3XDrawContextValidationClearFlags = 0x00000000,
  384.     kQ3XDrawContextValidationDoubleBuffer = 1 << 0,
  385.     kQ3XDrawContextValidationShader = 1 << 1,
  386.     kQ3XDrawContextValidationClearFunction = 1 << 2,
  387.     kQ3XDrawContextValidationActiveBuffer = 1 << 3,
  388.     kQ3XDrawContextValidationInternalOffScreen = 1 << 4,
  389.     kQ3XDrawContextValidationPane = 1 << 5,
  390.     kQ3XDrawContextValidationMask = 1 << 6,
  391.     kQ3XDrawContextValidationDevice = 1 << 7,
  392.     kQ3XDrawContextValidationWindow = 1 << 8,
  393.     kQ3XDrawContextValidationWindowSize = 1 << 9,
  394.     kQ3XDrawContextValidationWindowClip = 1 << 10,
  395.     kQ3XDrawContextValidationWindowPosition = 1 << 11,
  396.     kQ3XDrawContextValidationPlatformAttributes = 1 << 12,
  397.     kQ3XDrawContextValidationForegroundShader = 1 << 13,
  398.     kQ3XDrawContextValidationBackgroundShader = 1 << 14,
  399.     kQ3XDrawContextValidationColorPalette = 1 << 15,
  400.     kQ3XDrawContextValidationAll = (long)0xFFFFFFFF
  401. };
  402. typedef enum TQ3XDrawContextValidationMasks TQ3XDrawContextValidationMasks;
  403.  
  404. typedef unsigned long                     TQ3XDrawContextValidation;
  405. EXTERN_API_C( TQ3Status )
  406. Q3XDrawContext_ClearValidationFlags (TQ3DrawContextObject  drawContext);
  407.  
  408. EXTERN_API_C( TQ3Status )
  409. Q3XDrawContext_GetValidationFlags (TQ3DrawContextObject  drawContext,
  410.                                  TQ3XDrawContextValidation * validationFlags);
  411.  
  412.  
  413. /******************************************************************************
  414.  **                                                                             **
  415.  **                            Renderer Draw Region Tools                         **
  416.  **                                                                             **
  417.  *****************************************************************************/
  418.  
  419. enum TQ3XDevicePixelType {
  420.                                                                 /* These do not indicate byte ordering   */
  421.     kQ3XDevicePixelTypeInvalid    = 0,                            /* Unknown, un-initialized type     */
  422.     kQ3XDevicePixelTypeRGB32    = 1,                            /* Alpha:8 (ignored), R:8, G:8, B:8 */
  423.     kQ3XDevicePixelTypeARGB32    = 2,                            /* Alpha:8, R:8, G:8, B:8              */
  424.     kQ3XDevicePixelTypeRGB24    = 3,                            /* 24 bits/pixel, R:8, G:8, B:8     */
  425.     kQ3XDevicePixelTypeRGB16    = 4,                            /* Alpha:1 (ignored), R:5, G:5, B:5 */
  426.     kQ3XDevicePixelTypeARGB16    = 5,                            /* Alpha:1, R:5, G:5, B:5              */
  427.     kQ3XDevicePixelTypeRGB16_565 = 6,                            /* 16 bits/pixel, R:5, G:6, B:5     */
  428.     kQ3XDevicePixelTypeIndexed8    = 7,                            /* 8-bit color table index             */
  429.     kQ3XDevicePixelTypeIndexed4    = 8,                            /* 4-bit color table index             */
  430.     kQ3XDevicePixelTypeIndexed2    = 9,                            /* 2-bit color table index             */
  431.     kQ3XDevicePixelTypeIndexed1    = 10                            /* 1-bit color table index             */
  432. };
  433. typedef enum TQ3XDevicePixelType TQ3XDevicePixelType;
  434.  
  435.  
  436. enum TQ3XClipMaskState {
  437.     kQ3XClipMaskFullyExposed    = 0,
  438.     kQ3XClipMaskPartiallyExposed = 1,
  439.     kQ3XClipMaskNotExposed        = 2
  440. };
  441. typedef enum TQ3XClipMaskState TQ3XClipMaskState;
  442.  
  443.  
  444. struct TQ3XColorDescriptor {
  445.     unsigned long                     redShift;
  446.     unsigned long                     redMask;
  447.     unsigned long                     greenShift;
  448.     unsigned long                     greenMask;
  449.     unsigned long                     blueShift;
  450.     unsigned long                     blueMask;
  451.     unsigned long                     alphaShift;
  452.     unsigned long                     alphaMask;
  453. };
  454. typedef struct TQ3XColorDescriptor        TQ3XColorDescriptor;
  455.  
  456. struct TQ3XDrawRegionDescriptor {
  457.     unsigned long                     width;
  458.     unsigned long                     height;
  459.     unsigned long                     rowBytes;
  460.     unsigned long                     pixelSize;
  461.     TQ3XDevicePixelType             pixelType;
  462.     TQ3XColorDescriptor             colorDescriptor;
  463.     TQ3Endian                         bitOrder;
  464.     TQ3Endian                         byteOrder;
  465.     TQ3Bitmap *                        clipMask;
  466. };
  467. typedef struct TQ3XDrawRegionDescriptor    TQ3XDrawRegionDescriptor;
  468.  
  469. enum TQ3XDrawRegionServicesMasks {
  470.     kQ3XDrawRegionServicesNoneFlag = 0L,
  471.     kQ3XDrawRegionServicesClearFlag = 1 << 0,
  472.     kQ3XDrawRegionServicesDontLockDDSurfaceFlag = 1 << 1
  473. };
  474. typedef enum TQ3XDrawRegionServicesMasks TQ3XDrawRegionServicesMasks;
  475.  
  476.  
  477. typedef unsigned long                     TQ3XDrawRegionServices;
  478. typedef CALLBACK_API_C( void , TQ3XDrawRegionRendererPrivateDeleteMethod )(void *rendererPrivate);
  479. EXTERN_API_C( TQ3Status )
  480. Q3XDrawRegion_GetDeviceScaleX    (TQ3XDrawRegion         drawRegion,
  481.                                  float *                deviceScaleX);
  482.  
  483. EXTERN_API_C( TQ3Status )
  484. Q3XDrawRegion_GetDeviceScaleY    (TQ3XDrawRegion         drawRegion,
  485.                                  float *                deviceScaleY);
  486.  
  487.  
  488. EXTERN_API_C( TQ3Status )
  489. Q3XDrawRegion_GetDeviceOffsetX    (TQ3XDrawRegion         drawRegion,
  490.                                  float *                deviceOffsetX);
  491.  
  492. EXTERN_API_C( TQ3Status )
  493. Q3XDrawRegion_GetDeviceOffsetY    (TQ3XDrawRegion         drawRegion,
  494.                                  float *                deviceOffsetX);
  495.  
  496.  
  497. EXTERN_API_C( TQ3Status )
  498. Q3XDrawRegion_GetWindowScaleX    (TQ3XDrawRegion         drawRegion,
  499.                                  float *                windowScaleX);
  500.  
  501. EXTERN_API_C( TQ3Status )
  502. Q3XDrawRegion_GetWindowScaleY    (TQ3XDrawRegion         drawRegion,
  503.                                  float *                windowScaleY);
  504.  
  505.  
  506. EXTERN_API_C( TQ3Status )
  507. Q3XDrawRegion_GetWindowOffsetX    (TQ3XDrawRegion         drawRegion,
  508.                                  float *                windowOffsetX);
  509.  
  510. EXTERN_API_C( TQ3Status )
  511. Q3XDrawRegion_GetWindowOffsetY    (TQ3XDrawRegion         drawRegion,
  512.                                  float *                windowOffsetY);
  513.  
  514. EXTERN_API_C( TQ3Status )
  515. Q3XDrawRegion_IsActive            (TQ3XDrawRegion         drawRegion,
  516.                                  TQ3Boolean *            isActive);
  517.  
  518.  
  519. EXTERN_API_C( TQ3Status )
  520. Q3XDrawRegion_GetNextRegion        (TQ3XDrawRegion         drawRegion,
  521.                                  TQ3XDrawRegion *        nextDrawRegion);
  522.  
  523. /* 
  524.  *  One of the next two functions must be called before using a draw region 
  525.  */
  526. /*
  527.  *    Use this Start function if double buffering/image access services from the
  528.  *    Draw Context are not needed, you may still request clear for example
  529.  */
  530. EXTERN_API_C( TQ3Status )
  531. Q3XDrawRegion_Start                (TQ3XDrawRegion         drawRegion,
  532.                                  TQ3XDrawRegionServices  services,
  533.                                  TQ3XDrawRegionDescriptor ** descriptor);
  534.  
  535. /*
  536.  *    Use this Start function if double buffering or image access services from 
  537.  *  the Draw Context are needed.
  538.  */
  539. EXTERN_API_C( TQ3Status )
  540. Q3XDrawRegion_StartAccessToImageBuffer (TQ3XDrawRegion     drawRegion,
  541.                                  TQ3XDrawRegionServices  services,
  542.                                  TQ3XDrawRegionDescriptor ** descriptor,
  543.                                  void **                image);
  544.  
  545. /*
  546.  *    This function is used to indicate that access to a DrawRegion is ended.
  547.  */
  548. EXTERN_API_C( TQ3Status )
  549. Q3XDrawRegion_End                (TQ3XDrawRegion         drawRegion);
  550.  
  551. EXTERN_API_C( TQ3Status )
  552. Q3XDrawRegion_GetDeviceTransform (TQ3XDrawRegion         drawRegion,
  553.                                  TQ3Matrix4x4 **        deviceTransform);
  554.  
  555. EXTERN_API_C( TQ3Status )
  556. Q3XDrawRegion_GetClipFlags        (TQ3XDrawRegion         drawRegion,
  557.                                  TQ3XClipMaskState *    clipMaskState);
  558.  
  559. EXTERN_API_C( TQ3Status )
  560. Q3XDrawRegion_GetClipMask        (TQ3XDrawRegion         drawRegion,
  561.                                  TQ3Bitmap **            clipMask);
  562.  
  563. #if TARGET_OS_MAC
  564. EXTERN_API_C( TQ3Status )
  565. Q3XDrawRegion_GetClipRegion        (TQ3XDrawRegion         drawRegion,
  566.                                  RgnHandle *            rgnHandle);
  567.  
  568. EXTERN_API_C( TQ3Status )
  569. Q3XDrawRegion_GetGDHandle        (TQ3XDrawRegion         drawRegion,
  570.                                  GDHandle *                gdHandle);
  571.  
  572. #endif  /* TARGET_OS_MAC */
  573.  
  574. EXTERN_API_C( TQ3Status )
  575. Q3XDrawRegion_GetRendererPrivate (TQ3XDrawRegion         drawRegion,
  576.                                  void **                rendererPrivate);
  577.  
  578. EXTERN_API_C( TQ3Status )
  579. Q3XDrawRegion_SetRendererPrivate (TQ3XDrawRegion         drawRegion,
  580.                                  const void *            rendererPrivate,
  581.                                  TQ3XDrawRegionRendererPrivateDeleteMethod  deleteMethod);
  582.  
  583. EXTERN_API_C( TQ3Status )
  584. Q3XDrawRegion_SetUseDefaultRendererFlag (TQ3XDrawRegion  drawRegion,
  585.                                  TQ3Boolean             flag);
  586.  
  587. EXTERN_API_C( TQ3Status )
  588. Q3XDrawRegion_GetUseDefaultRendererFlag (TQ3XDrawRegion  drawRegion,
  589.                                  TQ3Boolean *            useDefaultRenderingFlag);
  590.  
  591.  
  592.  
  593. /******************************************************************************
  594.  **                                                                             **
  595.  **                            Renderer Class Methods                             **
  596.  **                                                                             **
  597.  *****************************************************************************/
  598. /*
  599.  *    Methods from Object
  600.  *        kQ3XMethodTypeObjectClassRegister
  601.  *        kQ3XMethodTypeObjectClassUnregister
  602.  *        kQ3XMethodTypeObjectNew
  603.  *        kQ3XMethodTypeObjectDelete
  604.  *        kQ3XMethodTypeObjectRead
  605.  *        kQ3XMethodTypeObjectTraverse
  606.  *        kQ3XMethodTypeObjectWrite
  607.  *        
  608.  *    Methods from Shared
  609.  *        kQ3MethodTypeSharedEdited
  610.  *
  611.  *    Renderer Methods
  612.  *    
  613.  *    The renderer methods should be implemented according to the type
  614.  *    of renderer being written.
  615.  *
  616.  *    For the purposes of documentation, there are two basic types of
  617.  *    renderers: 
  618.  *
  619.  *        Interactive
  620.  *            Interactive Renderer
  621.  *            WireFrame Renderer
  622.  *        
  623.  *        Deferred
  624.  *            a ray-tracer
  625.  *            painter's algorithm renderer (cached in a BSP triangle tree)
  626.  *            an artistic renderer (simulates a pencil drawing, etc.)
  627.  *
  628.  *    The main difference is how each renderer handles incoming state and 
  629.  *    geometry.
  630.  *
  631.  *    An interactive renderer immediately transforms, culls, and shades
  632.  *    incoming geometry and performs rasterization. For example, in a 
  633.  *    single-buffered WireFrame renderer, you will see a new triangle
  634.  *    immediately after Q3Triangle_Draw (if it's visible, of course).
  635.  *
  636.  *    A deferred renderer caches the view state and each geometry, 
  637.  *    converting into any internal queue of drawing commands. Rasterization
  638.  *    is not actually performed until all data has been submitted.
  639.  *    
  640.  *    For example, a ray-tracer may not rasterize anything until the
  641.  *    end of the rendering loop, or until an EndFrame call is made.
  642.  */
  643.  
  644. /******************************************************************************
  645.  **                                                                             **
  646.  **                        Renderer User Interface Methods                         **
  647.  **                                                                             **
  648.  *****************************************************************************/
  649. /*
  650.  *    kQ3XMethodTypeRendererIsInteractive
  651.  *    
  652.  *    There is no actual method with this - the metahandler simply returns
  653.  *  "(TQ3XFunctionPointer)kQ3True" for this "method" if the renderer is 
  654.  *  intended to be used in interactive settings, and   
  655.  *    "(TQ3XFunctionPointer)kQ3False" otherwise. 
  656.  *  
  657.  *  If neither value is specified in the metahandler, the renderer 
  658.  *  is *assumed to be non-interactive*!!!
  659.  *    
  660.  *    OPTIONAL
  661.  */
  662. enum {
  663.     kQ3XMethodTypeRendererIsInteractive = FOUR_CHAR_CODE('isin')
  664. };
  665.  
  666.  
  667. /*
  668.  *    TQ3XRendererModalConfigureMethod
  669.  *    
  670.  *    This method should pop up a modal dialog to edit the renderer settings 
  671.  *    found in the renderer private. 
  672.  *    
  673.  *    dialogAnchor - is platform specific data passed by the client to support
  674.  *      movable modal dialogs. 
  675.  *    MacOS: this is a callback to the calling application's event handler.
  676.  *      The renderer calls this function with events not handled by the 
  677.  *      settings dialog. This is necessary in order to support movable modal 
  678.  *      dialogs. An application's event handler must return kQ3True if it 
  679.  *      handles the event passed to the callback or kQ3False if not. 
  680.  *      An application which doesn't want to support a movable modal configure
  681.  *      dialog should pass NULL for the clientEventHandler of TQ3DialogAnchor.
  682.  *      A renderer should implement a non-movable style dialog in that case.
  683.  *    Win32: this is the HWND of the owning window (typically an application's
  684.  *      main window).  (Win32 application modal dialogs are always movable.)
  685.  *  canceled - returns a boolean inditacating that the user canceled the 
  686.  *    dialog.
  687.  *    
  688.  *    OPTIONAL
  689.  */
  690. enum {
  691.     kQ3XMethodTypeRendererModalConfigure = FOUR_CHAR_CODE('rdmc')
  692. };
  693.  
  694. typedef CALLBACK_API_C( TQ3Status , TQ3XRendererModalConfigureMethod )(TQ3RendererObject renderer, TQ3DialogAnchor dialogAnchor, TQ3Boolean *canceled, void *rendererPrivate);
  695. /*
  696.  *    kQ3XMethodTypeRendererGetNickNameString
  697.  *    
  698.  *        Allows an application to collect the name of the renderer for
  699.  *        display in a user interface item such as a menu.
  700.  *    
  701.  *        If dataBuffer is NULL actualDataSize returns the required size in 
  702.  *        bytes of a data buffer large enough to store the renderer name. 
  703.  *
  704.  *      bufferSize is the actual size of the memory block pointed to by 
  705.  *        dataBuffer
  706.  *
  707.  *        actualDataSize - on return the actual number of bytes written to the
  708.  *        buffer or if dataBuffer is NULL the required size of dataBuffer
  709.  *
  710.  *    OPTIONAL
  711.  */
  712. enum {
  713.     kQ3XMethodTypeRendererGetNickNameString = FOUR_CHAR_CODE('rdns')
  714. };
  715.  
  716. typedef CALLBACK_API_C( TQ3Status , TQ3XRendererGetNickNameStringMethod )(unsigned char *dataBuffer, unsigned long bufferSize, unsigned long *actualDataSize);
  717. /*
  718.  *    kQ3XMethodTypeRendererGetConfigurationData
  719.  *    
  720.  *        Allows an application to collect private configuration data from the
  721.  *      renderer which it will then save. For example in a preference file, 
  722.  *      a registry key (on Windows) or in a style template. An application 
  723.  *      should tag this data with the renderer's object name.
  724.  *    
  725.  *        If dataBuffer is NULL actualDataSize returns the required size in 
  726.  *        bytes of a data buffer large enough to store private data. 
  727.  *
  728.  *      bufferSize is the actual size of the memory block pointed to by 
  729.  *        dataBuffer
  730.  *
  731.  *        actualDataSize - on return the actual number of bytes written to the
  732.  *        buffer or if dataBuffer is NULL the required size of dataBuffer
  733.  *
  734.  *    OPTIONAL
  735.  */
  736. enum {
  737.     kQ3XMethodTypeRendererGetConfigurationData = FOUR_CHAR_CODE('rdgp')
  738. };
  739.  
  740. typedef CALLBACK_API_C( TQ3Status , TQ3XRendererGetConfigurationDataMethod )(TQ3RendererObject renderer, unsigned char *dataBuffer, unsigned long bufferSize, unsigned long *actualDataSize, void *rendererPrivate);
  741. /*
  742.  *    TQ3XRendererSetConfigurationDataMethod
  743.  *    
  744.  *        Allows an application to pass private configuration data which has
  745.  *         previously  been obtained from a renderer via 
  746.  *        Q3Renderer_GetConfigurationData. For example in a preference file or 
  747.  *        in a style template. An application should tag this data with the 
  748.  *        renderer's object name.
  749.  *    
  750.  *      bufferSize is the actual size of the memory block pointed to by 
  751.  *        dataBuffer
  752.  *
  753.  *    OPTIONAL
  754.  */
  755. enum {
  756.     kQ3XMethodTypeRendererSetConfigurationData = FOUR_CHAR_CODE('rdsp')
  757. };
  758.  
  759. typedef CALLBACK_API_C( TQ3Status , TQ3XRendererSetConfigurationDataMethod )(TQ3RendererObject renderer, unsigned char *dataBuffer, unsigned long bufferSize, void *rendererPrivate);
  760. /******************************************************************************
  761.  **                                                                             **
  762.  **                        Renderer Drawing State Methods                         **
  763.  **                                                                             **
  764.  *****************************************************************************/
  765. /*
  766.  *    TQ3RendererStartFrame
  767.  *    
  768.  *    The StartFrame method is called first at Q3View_StartRendering
  769.  *    and should:
  770.  *        - initialize any renderer state to defaults
  771.  *        - extract any and all useful data from the drawContext
  772.  *
  773.  *    If your renderer passed in kQ3RendererFlagClearBuffer at 
  774.  *    registration, then it should also:
  775.  *        - clear the drawContext 
  776.  *    
  777.  *        When clearing, your renderer may opt to:
  778.  *        - NOT clear anything (if you touch every pixel, for example)
  779.  *        - to clear with your own routine, or
  780.  *        - to use the draw context default clear method by calling 
  781.  *        Q3DrawContext_Clear. Q3DrawContext_Clear takes advantage of
  782.  *        any available hardware in the system for clearing.
  783.  *    
  784.  *    This call also signals the start of all default submit commands from
  785.  *    the view. The renderer will receive updates for the default view
  786.  *    state via its Update methods before StartPass is called.
  787.  *    
  788.  *    REQUIRED
  789.  */
  790. enum {
  791.     kQ3XMethodTypeRendererStartFrame = FOUR_CHAR_CODE('rdcl')
  792. };
  793.  
  794. typedef CALLBACK_API_C( TQ3Status , TQ3XRendererStartFrameMethod )(TQ3ViewObject view, void *rendererPrivate, TQ3DrawContextObject drawContext);
  795. /*
  796.  *    kQ3XMethodTypeRendererStartPass
  797.  *    TQ3XRendererStartPassMethod
  798.  *    
  799.  *    The StartPass method is called during Q3View_StartRendering but after
  800.  *    the StartFrame command. It should:
  801.  *        - collect camera and light information
  802.  *    
  803.  *    If your renderer supports deferred camera transformation, camera is the
  804.  *    main camera which will be submitted in the hierarchy somewhere. It
  805.  *    is never NULL.
  806.  *
  807.  *    If your renderer does not support deferred camera transformation, camera
  808.  *    is the transformed camera.
  809.  *
  810.  *    If your renderer supports deferred light transformation, lights will be
  811.  *    NULL, and will be submitted to your light draw methods instead.
  812.  *
  813.  *    This call signals the end of the default update state, and the start of 
  814.  *  submit commands from the user to the view.
  815.  *
  816.  *    REQUIRED
  817.  */
  818. enum {
  819.     kQ3XMethodTypeRendererStartPass = FOUR_CHAR_CODE('rdst')
  820. };
  821.  
  822. typedef CALLBACK_API_C( TQ3Status , TQ3XRendererStartPassMethod )(TQ3ViewObject view, void *rendererPrivate, TQ3CameraObject camera, TQ3GroupObject lightGroup);
  823. /*
  824.  *    kQ3XMethodTypeRendererFlushFrame
  825.  *    TQ3XRendererFlushFrameMethod
  826.  *    
  827.  *    This call is only implemented by asynchronous renderers.
  828.  *    
  829.  *    The FlushFrame method is called between the StartPass and EndPass
  830.  *    methods and is called when the user wishes to flush any asynchronous
  831.  *    drawing tasks (which draw to the drawcontext), but does not want 
  832.  *    to block.
  833.  *    
  834.  *    The result of this call is that an image should "eventually" appear
  835.  *    asynchronously.
  836.  *    
  837.  *    For asynchronous rendering, this call is non-blocking.
  838.  *    
  839.  *    An interactive renderer should ensure that all received
  840.  *    geometries are drawn in the image.
  841.  *    
  842.  *    An interactive renderer that talks to hardware should force
  843.  *    the hardware to generate an image.
  844.  *    
  845.  *    A deferred renderer should exhibit a similar behaviour,
  846.  *    though it is not required.  A deferred renderer should spawn
  847.  *    a process that generates a partial image from the currently
  848.  *    accumulated drawing state. 
  849.  *    
  850.  *    However, for renderers such as ray-tracers which generally are
  851.  *    quite compute-intensive, FlushFrame is not required and is a no-op.
  852.  *
  853.  *    OPTIONAL
  854.  */
  855. enum {
  856.     kQ3XMethodTypeRendererFlushFrame = FOUR_CHAR_CODE('rdfl')
  857. };
  858.  
  859. typedef CALLBACK_API_C( TQ3Status , TQ3XRendererFlushFrameMethod )(TQ3ViewObject view, void *rendererPrivate, TQ3DrawContextObject drawContext);
  860. /*
  861.  *    kQ3XMethodTypeRendererEndPass
  862.  *    TQ3XRendererEndPassMethod
  863.  *    
  864.  *    The EndPass method is called at Q3View_EndRendering and signals
  865.  *    the end of submit commands to the view.
  866.  *
  867.  *    If an error occurs, the renderer should call Q3XError_Post and
  868.  *    return kQ3ViewStatusError.
  869.  *    
  870.  *    If a renderer requires another pass on the renderering data,
  871.  *    it should return kQ3ViewStatusRetraverse.
  872.  *    
  873.  *    If rendering was cancelled, this function will not be called
  874.  *    and the view will handle returning kQ3ViewStatusCancelled;
  875.  *    
  876.  *    Otherwise, your renderer should begin completing the process of 
  877.  *    generating the image in the drawcontext. If you have buffered
  878.  *    any drawing data, flush it. RendererEnd should have a similar
  879.  *    effect as RendererFlushFrame.
  880.  *    
  881.  *    If the renderer is synchronous:
  882.  *        - complete rendering of the entire frame
  883.  *        if the renderer supports kQ3RendererClassSupportDoubleBuffer
  884.  *            - Update the front buffer
  885.  *        else
  886.  *            - DrawContext will update the front buffer after returning
  887.  *
  888.  *    If the renderer is asynchronous
  889.  *        - spawn rendering thread for entire frame
  890.  *        if the renderer supports kQ3RendererClassSupportDoubleBuffer,
  891.  *            - you must eventually update the front buffer asynchronously
  892.  *        else
  893.  *            - you must eventually update the back buffer asynchronously
  894.  *            
  895.  *    REQUIRED
  896.  */
  897. enum {
  898.     kQ3XMethodTypeRendererEndPass = FOUR_CHAR_CODE('rded')
  899. };
  900.  
  901. typedef CALLBACK_API_C( TQ3ViewStatus , TQ3XRendererEndPassMethod )(TQ3ViewObject view, void *rendererPrivate);
  902. /*
  903.  *    kQ3XMethodTypeRendererEndFrame
  904.  *    TQ3XRendererEndFrame
  905.  *    
  906.  *    This call is only implemented by asynchronous renderers.
  907.  *
  908.  *    The EndFrame method is called from Q3View_Sync, which is
  909.  *    called after Q3View_EndRendering and signals that the user
  910.  *    wishes to see the completed image and is willing to block.
  911.  *    
  912.  *    If your renderer supports kQ3RendererFlagDoubleBuffer
  913.  *        - update the front buffer completely 
  914.  *    else
  915.  *        - update the back buffer completely
  916.  *
  917.  *    This call is equivalent in functionality to RendererFlushFrame
  918.  *    but blocks until the image is completed.
  919.  *    
  920.  *    If no method is supplied, the default is a no-op.
  921.  *    
  922.  *    NOTE: Registering a method of this type indicates that your renderer will
  923.  *    be rendering after Q3View_EndRendering has been called.
  924.  *    
  925.  *    OPTIONAL
  926.  */
  927. enum {
  928.     kQ3XMethodTypeRendererEndFrame = FOUR_CHAR_CODE('rdsy')
  929. };
  930.  
  931. typedef CALLBACK_API_C( TQ3Status , TQ3XRendererEndFrameMethod )(TQ3ViewObject view, void *rendererPrivate, TQ3DrawContextObject drawContext);
  932. /*
  933.  *    The RendererCancel method is called after Q3View_StartRendering
  934.  *    and signals the termination of all rendering operations.
  935.  *
  936.  *    A renderer should clean up any cached data, and cancel all 
  937.  *    rendering operations.
  938.  *    
  939.  *    If called before Q3View_EndRendering, the RendererEnd method
  940.  *    is NOT called.
  941.  *    
  942.  *    If called after Q3View_EndRendering, the renderer should kill
  943.  *    any threads and terminate any further rendering.
  944.  *    
  945.  *    REQUIRED
  946.  */
  947. enum {
  948.     kQ3XMethodTypeRendererCancel = FOUR_CHAR_CODE('rdab')
  949. };
  950.  
  951. typedef CALLBACK_API_C( void , TQ3XRendererCancelMethod )(TQ3ViewObject view, void *rendererPrivate);
  952. /******************************************************************************
  953.  **                                                                             **
  954.  **                        Renderer DrawContext Methods                         **
  955.  **                                                                             **
  956.  *****************************************************************************/
  957. /*
  958.  *    kQ3XMethodTypeRendererPush
  959.  *    TQ3XRendererPushMethod
  960.  *    
  961.  *    kQ3XMethodTypeRendererPop
  962.  *    TQ3XRendererPopMethod
  963.  *    
  964.  *    These methods are called whenever the graphics state in the view
  965.  *    is pushed or popped. The user may isolate state by calling:
  966.  *    
  967.  *    Q3Attribute_Submit(kQ3AttributeTypeDiffuseColor, &red, view);
  968.  *    Q3Attribute_Submit(kQ3AttributeTypeTransparencyColor, &blue, view);
  969.  *    Q3Attribute_Submit(kQ3AttributeTypeSpecularColor, &white, view);
  970.  *    Q3Box_Submit(&unitBox, view);
  971.  *    Q3TranslateTransform_Submit(&unitVector, view);
  972.  *    Q3Push_Submit(view);
  973.  *        Q3Attribute_Submit(kQ3AttributeTypeDiffuseColor, &blue, view);
  974.  *        Q3Attribute_Submit(kQ3AttributeTypeTransparencyColor, &green, view);
  975.  *        Q3Box_Submit(&unitBox, view);
  976.  *    Q3Pop_Submit(view);    
  977.  *    Q3TranslateTransform_Submit(&unitVector, view);
  978.  *    Q3Box_Submit(&unitBox, view);
  979.  *    
  980.  *    or by submitting a display group which pushes and pops.
  981.  *    
  982.  *    If you support RendererPush and RendererPop in your renderer:
  983.  *        - you must maintain your drawing state as a stack, as well.
  984.  *        - you will not be updated with the popped state after
  985.  *            RendererPop is called.
  986.  *
  987.  *    If you do not support Push and Pop in your renderer:
  988.  *        - you may maintain a single copy of the drawing state.
  989.  *        - you will be updated with changed fields after the view stack is
  990.  *            popped.
  991.  *
  992.  *    A renderer that supports Push and Pop gets called in the following
  993.  *    sequence (from example above):
  994.  *    
  995.  *    RendererUpdateAttributeDiffuseColor(&red,...)
  996.  *    RendererUpdateAttributeTransparencyColor(&blue,...)
  997.  *    RendererUpdateAttributeSpecularColor(&white,...)
  998.  *    RendererUpdateMatrixLocalToWorld(...)
  999.  *    RendererSubmitGeometryBox(...)
  1000.  *    RendererPush(...)
  1001.  *        RendererUpdateAttributeDiffuseColor(&blue,...)
  1002.  *        RendererUpdateAttributeTransparencyColor(&green,...)
  1003.  *        RendererSubmitGeometryBox(...)
  1004.  *    RendererPop(...)
  1005.  *    RendererUpdateMatrixLocalToWorld(...)
  1006.  *    RendererSubmitGeometryBox(...)
  1007.  *
  1008.  *    A renderer that does not supports Push and Pop gets called in the
  1009.  *    following sequence:
  1010.  *    
  1011.  *    RendererUpdateAttributeDiffuseColor(&red,...)
  1012.  *    RendererUpdateAttributeTransparencyColor(&blue,...)
  1013.  *    RendererUpdateAttributeSpecularColor(&white,...)
  1014.  *    RendererUpdateMatrixLocalToWorld(...)
  1015.  *    RendererSubmitGeometryBox(...)
  1016.  *        RendererUpdateAttributeDiffuseColor(&blue,...)
  1017.  *        RendererUpdateAttributeTransparencyColor(&green,...)
  1018.  *        RendererSubmitGeometryBox(...)
  1019.  *    RendererUpdateAttributeDiffuseColor(&red,...)
  1020.  *    RendererUpdateAttributeTransparencyColor(&blue,...)
  1021.  *    RendererUpdateMatrixLocalToWorld(...)
  1022.  *    RendererSubmitGeometryBox(...)
  1023.  *    
  1024.  */
  1025. enum {
  1026.     kQ3XMethodTypeRendererPush    = FOUR_CHAR_CODE('rdps')
  1027. };
  1028.  
  1029. typedef CALLBACK_API_C( TQ3Status , TQ3XRendererPushMethod )(TQ3ViewObject view, void *rendererPrivate);
  1030. enum {
  1031.     kQ3XMethodTypeRendererPop    = FOUR_CHAR_CODE('rdpo')
  1032. };
  1033.  
  1034. typedef CALLBACK_API_C( TQ3Status , TQ3XRendererPopMethod )(TQ3ViewObject view, void *rendererPrivate);
  1035. /******************************************************************************
  1036.  **                                                                             **
  1037.  **                            Renderer Cull Methods                             **
  1038.  **                                                                             **
  1039.  *****************************************************************************/
  1040. /*
  1041.  *    kQ3XMethodTypeRendererIsBoundingBoxVisible
  1042.  *    TQ3XRendererIsBoundingBoxVisibleMethod
  1043.  *    
  1044.  *    This method is called to cull complex groups and geometries 
  1045.  *    given their bounding box in local space.
  1046.  *    
  1047.  *    It should transform the local-space bounding box coordinates to
  1048.  *    frustum space and return a TQ3Boolean return value indicating
  1049.  *    whether the box appears within the viewing frustum.
  1050.  *    
  1051.  *    If no method is supplied, the default behavior is to return
  1052.  *    kQ3True.
  1053.  *    
  1054.  */
  1055. enum {
  1056.     kQ3XMethodTypeRendererIsBoundingBoxVisible = FOUR_CHAR_CODE('rdbx')
  1057. };
  1058.  
  1059. typedef CALLBACK_API_C( TQ3Boolean , TQ3XRendererIsBoundingBoxVisibleMethod )(TQ3ViewObject view, void *rendererPrivate, const TQ3BoundingBox *bBox);
  1060.  
  1061. /******************************************************************************
  1062.  **                                                                             **
  1063.  **                        Renderer Object Support Methods                         **
  1064.  **                                                                             **
  1065.  *****************************************************************************/
  1066. /*
  1067.  *    Drawing methods (Geometry, Camera, Lights)
  1068.  *
  1069.  */
  1070. /*
  1071.  *    Geometry MetaHandler
  1072.  *    
  1073.  *    This metaHandler is required to support 
  1074.  *    
  1075.  *    kQ3GeometryTypeTriangle
  1076.  *    kQ3GeometryTypeLine
  1077.  *    kQ3GeometryTypePoint
  1078.  *    kQ3GeometryTypeMarker
  1079.  *    kQ3GeometryTypePixmapMarker
  1080.  *    
  1081.  *    REQUIRED
  1082.  */
  1083. enum {
  1084.     kQ3XMethodTypeRendererSubmitGeometryMetaHandler = FOUR_CHAR_CODE('rdgm')
  1085. };
  1086.  
  1087. typedef CALLBACK_API_C( TQ3XFunctionPointer , TQ3XRendererSubmitGeometryMetaHandlerMethod )(TQ3ObjectType geometryType);
  1088. /*
  1089.  *    The TQ3XRendererSubmitGeometryMetaHandlerMethod switches on geometryType
  1090.  *    of kQ3GeometryTypeFoo and returns methods of type:
  1091.  */
  1092. typedef CALLBACK_API_C( TQ3Status , TQ3XRendererSubmitGeometryMethod )(TQ3ViewObject view, void *rendererPrivate, TQ3GeometryObject geometry, const void *publicData);
  1093. /*
  1094.  *    Camera MetaHandler
  1095.  *    
  1096.  *    This metaHandler, if supplied, indicates that your renderer
  1097.  *    handles deferred transformation of the main camera within a scene.
  1098.  *    
  1099.  *    If not supplied, or an unsupported camera is used, the view will do
  1100.  *    the transformation for the renderer and pass in a camera in the 
  1101.  *    StartPass method.
  1102.  *    
  1103.  *    OPTIONAL
  1104.  */
  1105. enum {
  1106.     kQ3XMethodTypeRendererSubmitCameraMetaHandler = FOUR_CHAR_CODE('rdcm')
  1107. };
  1108.  
  1109. typedef CALLBACK_API_C( TQ3XFunctionPointer , TQ3XRendererSubmitCameraMetaHandlerMethod )(TQ3ObjectType cameraType);
  1110. /*
  1111.  *    The TQ3XRendererSubmitCameraMetaHandlerMethod switches on cameraType
  1112.  *    of kQ3CameraTypeFoo and returns methods of type:
  1113.  */
  1114. typedef CALLBACK_API_C( TQ3Status , TQ3XRendererSubmitCameraMethod )(TQ3ViewObject view, void *rendererPrivate, TQ3CameraObject camera, const void *publicData);
  1115. /*
  1116.  *    Light MetaHandler
  1117.  *    
  1118.  *    This metaHandler, if supplied, indicates that your renderer
  1119.  *    handles deferred transformation of lights within a scene.
  1120.  *    
  1121.  *    If an unsupported light is encountered, it is ignored.
  1122.  *
  1123.  *    OPTIONAL
  1124.  */
  1125. enum {
  1126.     kQ3XMethodTypeRendererSubmitLightMetaHandler = FOUR_CHAR_CODE('rdlg')
  1127. };
  1128.  
  1129. typedef CALLBACK_API_C( TQ3XFunctionPointer , TQ3XRendererSubmitLightMetaHandlerMethod )(TQ3ObjectType lightType);
  1130. /*
  1131.  *    The TQ3XRendererSubmitLightMetaHandlerMethod switches on lightType
  1132.  *    of kQ3LightTypeFoo and returns methods of type:
  1133.  */
  1134. typedef CALLBACK_API_C( TQ3Status , TQ3XRendererSubmitLightMethod )(TQ3ViewObject view, void *rendererPrivate, TQ3LightObject light, const void *publicData);
  1135. /*
  1136.  *
  1137.  *    Update methods
  1138.  *
  1139.  *    They are called whenever the state has changed. If the renderer supports
  1140.  *    the RendererPush and RendererPop methods, it must maintain its own state
  1141.  *    stack. Updates are not called for changed data when the view stack is
  1142.  *    popped.
  1143.  *
  1144.  *    See the comments for the RendererPush and RendererPop methods above
  1145.  *    for an example of how data is updated.
  1146.  *
  1147.  */
  1148. /*
  1149.  *    Style
  1150.  */
  1151. enum {
  1152.     kQ3XMethodTypeRendererUpdateStyleMetaHandler = FOUR_CHAR_CODE('rdyu')
  1153. };
  1154.  
  1155. typedef CALLBACK_API_C( TQ3XFunctionPointer , TQ3XRendererUpdateStyleMetaHandlerMethod )(TQ3ObjectType styleType);
  1156. /*
  1157.  *    The TQ3XRendererUpdateStyleMetaHandlerMethod switches on styleType
  1158.  *    of kQ3StyleTypeFoo and returns methods of type:
  1159.  */
  1160. typedef CALLBACK_API_C( TQ3Status , TQ3XRendererUpdateStyleMethod )(TQ3ViewObject view, void *rendererPrivate, const void *publicData);
  1161. /*
  1162.  *    Attributes
  1163.  */
  1164. enum {
  1165.     kQ3XMethodTypeRendererUpdateAttributeMetaHandler = FOUR_CHAR_CODE('rdau')
  1166. };
  1167.  
  1168. typedef CALLBACK_API_C( TQ3XFunctionPointer , TQ3XRendererUpdateAttributeMetaHandlerMethod )(TQ3AttributeType attributeType);
  1169. /*
  1170.  *    The TQ3XRendererUpdateStyleMetaHandlerMethod switches on attributeType
  1171.  *    of kQ3AttributeTypeFoo and returns methods of type:
  1172.  */
  1173. typedef CALLBACK_API_C( TQ3Status , TQ3XRendererUpdateAttributeMethod )(TQ3ViewObject view, void *rendererPrivate, const void *publicData);
  1174. /*
  1175.  *    Shaders
  1176.  */
  1177. enum {
  1178.     kQ3XMethodTypeRendererUpdateShaderMetaHandler = FOUR_CHAR_CODE('rdsu')
  1179. };
  1180.  
  1181. typedef CALLBACK_API_C( TQ3XFunctionPointer , TQ3XRendererUpdateShaderMetaHandlerMethod )(TQ3ObjectType shaderType);
  1182. /*
  1183.  *    The TQ3XRendererUpdateShaderMetaHandlerMethod switches on shaderType
  1184.  *    of kQ3ShaderTypeFoo and returns methods of type:
  1185.  */
  1186. typedef CALLBACK_API_C( TQ3Status , TQ3XRendererUpdateShaderMethod )(TQ3ViewObject view, void *rendererPrivate, TQ3Object *shaderObject);
  1187. /*
  1188.  *    Matrices
  1189.  */
  1190. enum {
  1191.     kQ3XMethodTypeRendererUpdateMatrixMetaHandler = FOUR_CHAR_CODE('rdxu')
  1192. };
  1193.  
  1194. typedef TQ3XMetaHandler                 TQ3XRendererUpdateMatrixMetaHandlerMethod;
  1195. /*
  1196.  *    The TQ3XRendererUpdateShaderMetaHandlerMethod switches on methods
  1197.  *    of the form kQ3MethodTypeRendererUpdateMatrixFoo:
  1198.  */
  1199. enum {
  1200.     kQ3XMethodTypeRendererUpdateMatrixLocalToWorld = FOUR_CHAR_CODE('ulwx')
  1201. };
  1202.  
  1203. enum {
  1204.     kQ3XMethodTypeRendererUpdateMatrixLocalToWorldInverse = FOUR_CHAR_CODE('ulwi')
  1205. };
  1206.  
  1207. enum {
  1208.     kQ3XMethodTypeRendererUpdateMatrixLocalToWorldInverseTranspose = FOUR_CHAR_CODE('ulwt')
  1209. };
  1210.  
  1211. enum {
  1212.     kQ3XMethodTypeRendererUpdateMatrixLocalToCamera = FOUR_CHAR_CODE('ulcx')
  1213. };
  1214.  
  1215. enum {
  1216.     kQ3XMethodTypeRendererUpdateMatrixLocalToFrustum = FOUR_CHAR_CODE('ulfx')
  1217. };
  1218.  
  1219. enum {
  1220.     kQ3XMethodTypeRendererUpdateMatrixWorldToFrustum = FOUR_CHAR_CODE('uwfx')
  1221. };
  1222.  
  1223. /*
  1224.  *    and returns methods of type:
  1225.  */
  1226. typedef CALLBACK_API_C( TQ3Status , TQ3XRendererUpdateMatrixMethod )(TQ3ViewObject view, void *rendererPrivate, const TQ3Matrix4x4 *matrix);
  1227.  
  1228.  
  1229. #if PRAGMA_ENUM_ALWAYSINT
  1230.     #pragma enumsalwaysint reset
  1231. #elif PRAGMA_ENUM_OPTIONS
  1232.     #pragma option enum=reset
  1233. #elif defined(PRAGMA_ENUM_PACK__QD3DRENDERER__)
  1234.     #pragma options(pack_enums)
  1235. #endif
  1236.  
  1237. #if PRAGMA_STRUCT_ALIGN
  1238.     #pragma options align=reset
  1239. #elif PRAGMA_STRUCT_PACKPUSH
  1240.     #pragma pack(pop)
  1241. #elif PRAGMA_STRUCT_PACK
  1242.     #pragma pack()
  1243. #endif
  1244.  
  1245. #ifdef PRAGMA_IMPORT_OFF
  1246. #pragma import off
  1247. #elif PRAGMA_IMPORT
  1248. #pragma import reset
  1249. #endif
  1250.  
  1251. #ifdef __cplusplus
  1252. }
  1253. #endif
  1254.  
  1255. #endif /* __QD3DRENDERER__ */
  1256.  
  1257.